home *** CD-ROM | disk | FTP | other *** search
/ Amiga Magazin: Amiga-CD 1997 September & October / Amiga-CD 1997 #9-10.iso / aminet / newyork / newyork.guide (.txt) < prev    next >
Amigaguide Document  |  1997-06-11  |  17KB  |  278 lines
  1.    **************************************************************************
  2.    ** THIS FILE CONTAINS IMPORTANT INFORMATION. PLEASE READ IT COMPLETELY. **
  3.    **************************************************************************
  4.                               NewYork V1 r201 DEMO
  5.                        Copyright 1996-1997 Finale Development, Inc.
  6.                          Written by Christopher E. Aldi
  7.                                     Credits
  8.                                     ~~~~~~~
  9.                      Source Contributions And Support From;
  10.           Dan Murrell (danimal) for help with all kinds of neat stuff.
  11.            Osma Ahvenlampi (Tau) for Quote-Printable/Base64 Examples
  12.                 (DarkDesgn) for help with the ActiveList Parser
  13.                       ClassAct GUI is Copyright 1995-1997
  14.                                      by the
  15.                            ClassAct Development Team
  16.         Christopher Aldi, Tim Aston, Osma Ahvenlampi and Petter Nilsen.
  17.                                Installing NewYork
  18.                                ~~~~~~~~~~~~~~~~~~
  19. To  install  NewYork,  just  click on the Install script provided.  You can also
  20. just  run  it  from  the directory.  NewYork does not require any assignments or
  21. external  files  other  than the ClassAct GUI.  The Install script will copy the
  22. required ClassAct GUI to your system if you do not have them already.
  23.                                Function Overview
  24.                                ~~~~~~~~~~~~~~~~~
  25. First,  it  should  be said that while a number of things and NewYork are fairly
  26. usable  at  this  point in time, not everything has been implemented, enabled or
  27. debuged.   The  overall design is not expected to change much betweeen this beta
  28. release  and final release.  However, suggestions/comments are welcome.  If they
  29. can not be applied to this work in progress, they could be applied to some later
  30. upgraded release and steps taken now to make doing so less painful later.
  31. Some noteworthy features include;
  32.  o Progressive article retrieval.
  33.  o News posting.
  34.  o News post reply via News or E-Mail.
  35.  o Configurable External E-Mailer (ie. Voodoo, Yam, etc)
  36.  o Hierarchical subscription list manager window.
  37.  o NNTP User Authorization, the two most common of three forms implemented.
  38.  o Fast news header retrieval w/local disk cache option.
  39.  o Automatically trims its own data files "on the fly".
  40.  o Program "SpeedBar" for easy control of common functions.
  41.  o Optional "SpeedTips" popup help system (req. V43 window.class)
  42.  o UUDecoder - can be either the currently displayed article, a
  43.    diskfile or a group of selected article(s).
  44.  o Font and Screen Mode preferences.
  45.  o Optional in-window clock.
  46.  o Simple (but growing!) ARexx port.
  47.  o Mark articles as read/unread.
  48.  o Shows the number of available articles and the number unread.
  49.  o Remembers, and optionally filters out, read articles between sessions.
  50.  o Articles sorted by Subject, Author, or NNTP Server ID.
  51.  o Optional "low-memory" configuration mode for 2M users.
  52. A few notes are in order.  The SpeedTips system is something new in ClassAct 2.1
  53. beta which is not available to everyone yet.  However, if your ClassAct is older
  54. you  simply  will  not have this help (simular to bubble help), but NewYork will
  55. continue to function.  News posting/followup is not totally completed yet but it
  56. will post your articles.  Additional note, with ClassAct 2.0 V42.52 window.class
  57. I have enabled the speedtips system via presently undocumented means.  To enable
  58. or disable this help in the main window, press the HELP key.
  59. Note  well,  XOVER and XHDR are draft standards, that means not all news servers
  60. will  support  these  new methods of retrieving news.  The final newyork NewYork
  61. will  fall back to RFC977 compliant HEAD or ARTICLE server commands in the event
  62. the XOVER or XHDR system should fail.  
  63. The  default  set  up  is for XOVER, however you may select XHDR in preferences.
  64. The  XOVER  system  transfers  (atleast)  8  important  fields  from the article
  65. headers.  NewYork retrieves thus XOVER information in a batch.  About 4 of the 8
  66. fields  are of interest to NewYork at this time.  The XHDR system allows NewYork
  67. to  specify  some  specific  single  field.   This  method can be faster, but is
  68. largely  server  implementation  dependant.   In  the  current NewYork, only the
  69. Subject:   is retrived.  The From:  and Date:  fields are NOT retrieved until an
  70. article  is  selected.   Thus,  XHDR  potentially  uses  less memory than XOVER.
  71. However, XHDR is not as well debugged or complete as the XOVER implementation at
  72. this  time.  In XHDR mode, the article size is Bytes is also unavailable, having
  73. this  information can speed up retrieval of larger articles.  For the time being
  74. the standard/default XOVER method is highly recommended.
  75.                                   Posting News
  76.                                   ~~~~~~~~~~~~
  77. To  post  a  new  article,  you  must  select  news  composition button from the
  78. speedbar.  The composition/editor window will then open.  The news group to post
  79. the  article too will that of the currently selected news group, i.e., the group
  80. currently  being  read.   You must then type in the subject of your post, unless
  81. you  are  following  up  to the current article, in this case, the subject field
  82. will  automatically  be filled out for you.  You may select a different group to
  83. post  to from a small list by clicking the popup gadget just to the right of the
  84. group  string  gadget.   Cross-posting  by  selecting multiple groups is not yet
  85. supported.   Once  you  have  composed  your  message, you should then click the
  86. post/send  button  in  the  composition  speedbar.   At  any time you may cancel
  87. posting an article by clicking the window's close button.
  88. The  article header, body and signature will then be created as a temporary file
  89. in T:  prior to being posted.  Durring the beta period, this file is NOT deleted
  90. after  the  post.   In the case of failure the header content may be valuable in
  91. finding bugs in the article composition/posting system.  It should be also noted
  92. that the signature appended to your article is taken from an optional file named
  93. "PROGDIR:NewYork.Signature".  That is to say, "NewYork.Signature" is loaded from
  94. the programs working directory if found.  This file name and location may become
  95. a user preference in the future.
  96.                           Preferences & Configuration
  97.                           ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  98. The first thing you must do is configure newyork, I know, everyone hates this
  99. part, and the beta testers certainly have done & re-done it often. :)
  100. In  NewYork  preferences, you will find a click-tab gadget across the top of the
  101. window.   This  organizes  preferences  by  function/catagory.   The  catagories
  102. include; General, Display, Fonts, Program, NetWork, and Encoding.
  103. On  the  General  page  you  must  fill in the four (4) string gadgets with your
  104. personal  data,  ie;  your email address, real name, organization (optional) and
  105. your reply (usually the same as your email address).
  106. On the Display page you can change the screen mode used by NewYork, be it on the
  107. Workbench, a Custom screen, etc.  You may also adjust the palette of your custom
  108. screen  usingthe  handly  palette  gadget and RGB sliders.  If you intend to run
  109. NewYork  on the workbench, you do not have to change anything, the defaults will
  110. be fine.
  111. On  the  Fonts  page  you  may  adjust  the  fonts used in various places within
  112. NewYork.   You  may select the interface font (the font that is used for the GUI
  113. when  on  a  custom screen), the message font (the font used to display the news
  114. article)  and  the  index  font  (the font used to display the group and article
  115. listviews).   NewYork  should  function  normally with the default settings, but
  116. feel free to experiment with different font settings.
  117. On  the  Program  page you may set various program related settings.  Here again
  118. NewYork  will  function  with  the  defaults,  however,  you will likely want to
  119. configure   the  path  and  arguments  for  your  email  program.   The  default
  120. configuration  is  set  up to use the "Voodoo" email client.  You need only edit
  121. the  path  to  the  executable program.  For other emailers, consult your mailer
  122. documentation for use as a plug-in via command line arguments.  In addition you
  123. may wish to enable the 'Cache Headers' option.  Enabling this will cause NewYork
  124. to  save  (cache)  header data (ie; Subject:, From:, Date:, etc) to a small disk
  125. data  file.   When revisiting a news group, this cache is reloaded and only news
  126. article  headers  not present in the cache are downloaded from the server.  This
  127. makes NewYork *MUCH* faster to use, especially notiable on large & highly active
  128. groups.
  129. On  the  NetWork  page you must set your NNTP news server address.  As a rule of
  130. thumb, if you email address is 'moocow@grassfarm.net' then your news server will
  131. likely  be  called  'news.grassfarm.net'.   NewYork tries to figure out the news
  132. server  name  if  it can, but you should confirm this information which your ISP
  133. should  have  made available to you.  The default "port" for news is 119, unless
  134. your  ISP  directed  you  to use something else, you should except this standard
  135. default  setting.   Some  ISP  news servers require authorizations to do certain
  136. functions  such  as  posting news, or downloading the servers active group list.
  137. NewYork  supports two of the three known standards.  If your ISP requires a news
  138. server login name and password, this is the authorization information, it may or
  139. may not be the same as your ISP user login and password.
  140.                               Subscription Editor
  141.                               ~~~~~~~~~~~~~~~~~~~
  142. The  next  thing  you will want to do with NewYork is download the group active
  143. list  from  the  news  server.  Most news servers carry atleast 15,000 to 35,000
  144. groups.   Thus, the active file is generally 500K to possibly over 1M, depending
  145. on  the speed of your network connection, this could take several minutes.  Once
  146. you  have  the list, NewYork will parse the active list to its own custom sorted
  147. hierarchical subscription resource format. This format is significantly smaller
  148. than the format received from the server, yielding a data file approximatly 150K
  149. to 300K.
  150. Such  a  large  list  can  be  difficult  to manage, in both user interface, and
  151. programmatically  sorting  and/or  processing such data .  NewYork presents this
  152. large  list  as a hierarchical group tree list.  For example, rather than a list
  153. of groups like so;
  154. --------------------------------
  155. comp.sys.amiga.advocacy
  156. comp.sys.amiga.announce
  157. comp.sys.amiga.programmer
  158. comp.sys.atari.advocacy
  159. comp.sys.atari.programmer
  160. --------------------------------
  161. NewYork visually organizes the groups in a tree like so;
  162. --------------------------------
  163. + comp
  164.    + sys
  165.        + amiga
  166.              advocacy
  167.              announce
  168.              programmer
  169.        + atari
  170.              advocacy
  171.              programmer
  172. --------------------------------
  173. This may or may not confuse some of you, however once you try to use it it will
  174. quickly make sence.  Such listtrees are fairly common place in Windows, Mac, MUI
  175. and other interfaces.  The hierarchical tree makes handling a large list such as
  176. this much more managable because you can expand/colapse the group hierarchy to
  177. show or hide various groups.  For example you could colapse the list at the
  178. 'amiga' level like so;
  179. --------------------------------
  180. + comp
  181.    + sys
  182.        - amiga
  183.        + atari
  184.              advocacy
  185.              programmer
  186. --------------------------------
  187. By  default,  all  levels are colapsed yielding a short manageable list, you can
  188. then  move  to  an  appropriate section, such as alt or comp.  Expand the level,
  189. such  as  alt,  to reveal sub-catatories of binaries, source, etc.  And continue
  190. down in to the group tree.
  191. The  deepest/last  level  of  the  tree are actual groups, these have checkboxes
  192. beside  the  group  names.  Selecting the check box subscribes you to the group,
  193. like  wise an unchecking a checkbox unsubscribes you from that group.  The state
  194. of  these checkboxes are stored directly in newyork's custom resource data file.
  195. Memory  usage  for  the  subscription editor is keep fairly low compared to most
  196. other  modern  news  readers,  however,  it  can still requier as much as 2 to 4
  197. megabytes  of  memory  to build the list.  I have been unable to confirm it, but
  198. I've  been  told  mNews  can  use  as much as 8 megs, and perhaps more for large
  199. lists.   If you don't have the memory to spare, you can join a group "on demand"
  200. by  selecting  the  "Join  By Name" option from the project menu.  Here, you can
  201. simply type in the name of the group into the string gadget.  This will retrieve
  202. the   groups  article  list  immediatly.   Use  of  this  feature  is  presently
  203. discouraged  due to some remaining odd bug(s) - but it doesn't hurt to give it a
  204. try and cross your fingers! ;)
  205.                                 KeyBoard Control
  206.                                 ~~~~~~~~~~~~~~~~
  207. A great deal of NewYork can be controlled via the keyboard.
  208. The main window article text display can be controlled as so;
  209.     Space = Page down
  210.     BkSpc = Page up
  211. Cursor Up = Up 1 line
  212. Cursor Dn = Down 1 line
  213.         N = Read next article
  214.         P = Read previous article
  215. The main window group and article lists can be controlled as so;
  216.         7 = Top of list
  217.         1 = Bottom of list
  218.         8 = Up 1 line
  219.         2 = Down 1 line
  220.         9 = Page up
  221.         3 = Page down
  222.     Enter = Retrieve selected group, or article.
  223. The subscription window list functions in a simular fashion.
  224.                                      To Do
  225.                                      ~~~~~
  226. I  would  like  to  complete  the  following list of features for the future of
  227. NewYork.   Any other simple or useable feature suggestions are welcome.  However
  228. the  focus  now is to complete/polish the loose ends, freeze the feature set and
  229. focus on debugging any remaining bugs for release ASAP.
  230.  o Automatically ask user to download news group active list from
  231.    server upon initial configuration.
  232.  o News post file attachment.
  233.  o MIME Base64 Encoding/Decoding.
  234.  o More (useful) ARexx commands.
  235.  o KillFile Editor (Scoring Perhaps?)
  236.  o Replace use of textfield.gadget for article display with a more
  237.    efficient and customizable text display engine.
  238.                                      Thanks
  239.                                      ~~~~~~
  240. Far  from  a  complete list of those who have had a taste of NewYork and offered
  241. input  durring  development,  but  I'd  like to thank some of my most vocal beta
  242. testers for a job well done:
  243.  Rafael Munoz (Zonum) <zonum@shadow.net>
  244.  (Sibbi) <>
  245.  (frotz) <Frotz@op.net>
  246.  Greg Scott (NAN) <gscott@interramp.com>
  247.  Dan Murrell, Jr (danimal) <djm2@ra.msstate.edu>
  248.  Magnus Lilja (lilja) <lilja@lysator.liu.se>
  249.  Timothy J. Aston (Timmer)  <timmer@warped.com>
  250.  Mike Latinovich (SkyGuy) <mlatin@owens.ridgecrest.ca.us>
  251.  Scott Ellis (ScottE) <sellis@rohan.sdsu.edu>
  252.  Mark Beal (Bealy) <mbeal@thenet.co.uk>
  253.  Eric Webb (Foobar) <>
  254.  (TheBarron) <>
  255.  (NightSpd) <>
  256.  (NiteFlite) <>
  257.  Eric (RMerlin) <>
  258.                                   Legal Notes
  259.                                   ~~~~~~~~~~~
  260. NewYork is Copyright 1996-1997 by Christopher E. Aldi, of Finale Development, Inc.
  261. The  included BOOPSI gadget and image classes are part of ClassAct, Published by
  262. Finale Development, Inc.   For  information  about  using ClassAct in your own
  263. applications, drop by the web page at;
  264. http://thule.icenet.no/classact
  265. http://www.warped.com/~timmer/classact
  266. Or you may also contact me, Christopher Aldi via email; caldi@finale-dev.com
  267.                                    BugReports
  268.                                    ~~~~~~~~~~
  269. Please report any bugs, suggestions or quirks to me and I will try to address
  270. them as soon as possible.  A number of people have been testing NewYork for
  271. some time now, and it has proven itself reasonably stable, however, nothing
  272. or no one is perfect, especially a beta.  Getting detailed bug reports from
  273. users most helpful in this stage of development.  When reporting bugs it is
  274. most helpful to know the revision of newyork, any system hacks or patches
  275. being used, the last few things you did with NewYork before the crash or error,
  276. and if at all possible, any 'enforcer' output. Enforcer is a debuging tool
  277. that requires an MMU, it should be available on AmiNet.
  278.